Client authentication

The REST API can be configured by the administrator to use OAuth 2.0 authentication or HTTP basic authentication.

OAuth 2.0 is the industry-standard protocol for authorization. OAuth 2.0 allows a client application to request only the desired permissions (scopes) and then use a short-lived access token for performing the REST API requests.

HTTP Basic authentication is simpler to use, and based on sending a username and a password with all REST API requests.

With both methods of authentication, the authorization is based on roles and scopes (policy) which defines the allowed operations for a specific user.

Configuring REST applications

Before using the REST API, an application with roles and scopes (policies) must be configured on VoiceAI Connect (click here). The application configuration consist of a client ID and a client secret that are used for authentication, and a list of roles and scopes that define the allowed operations for the application.

Using HTTP basic authentication

For using HTTP basic authentication, you should use the client ID as the username and the client secret as the password. All operations allowed by the application's roles and scopes will be allowed for the client.

All REST API requests should include an Authorization header like the following (the value is built according to the client ID and client secret, as described in RFC 7617):

Authorization: Basic dXNlci1pZDpwYXNzd29yZA==

When using the curl utility, the following command-line option can be used for sending the header:

-u "client-ID:client-secret"

Using OAuth 2.0

Before the client can perform any REST API request, the client should use the client-credentials flow to request an access token from VoiceAI Connect (according to Section 4.4.2 of RFC 6749). The token request should contain the client ID and client secret. Permissions to the client are granted according to the application's roles and scopes.

The OAuth 2.0 client-credentials flow is illustrated below (VoiceAI Connect acting both as the Authorization server and as the Resource server):

The client's token request should look like this (where CLIENT_ID and CLIENT_SECRET should be replaced with the corresponding values of the application):

POST /oauth/token HTTP/1.1
Host: server.example.com
Accept: application/json
Content-Type: application/x-www-form-urlencoded

client_id=CLIENT_ID
&client_secret=CLIENT_SECRET
&grant_type=client_credentials

The response to the client from VoiceAI Connect looks like this:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "access_token": "ACCESS_TOKEN",
  ...
}

The client application should use the received access token for the REST API requests, sending it in an Authorization header (according to RFC 6750) like the following:

Authorization: Bearer ACCESS_TOKEN

VoiceAI Connect checks that the token is valid and the application has permission for the requested operation.

When the token expires, the client application should obtain a new access token by the same method described above.

If authorization fails, VoiceAI Connect responds to the client according to Section 3.1 of RFC 6750. The client should handle such failures and, if needed, obtain a new access token.

If the Authorization header is missing or the token has expired, the response will look like this:

HTTP/1.1 401 Unauthorized

If the requesting client doesn't have permission for the requested operation, the response will look like this:

HTTP/1.1 403 Forbidden